Create table uploader actions

Initiation

You can create new table uploader action by using the table action handler builder which is a method in js controller mappings. These are available fields of a table action handler builder:

• id (Required): The id of the action
• title (Required): The title of the action which will be shown in the table uploader actions selection
• description (Optional): The description of the action
• field (Optional): The field which allow user to provide custom parameter for the action. You can add multiple fields
  • optionsFn: By default, the field is a simple text box. If this function is provided, the field will be changed to select box, and you need to return a list of options
• transformFileFn (Optional): The transform file function which allow to tranform the input file before process.
• transformRowFn (Optional): The transform row function which allow to tranform the row data before process.
• validateRownFn (Optional): The validate row function which allow to validate the row data before process
• processRownFn (Optional): The process row function which will process the row
• afterRownFn (Optional): The function will be execute after a row is processed
• afterFileFn (Optional): The function will be executed after the input file is processed

If the optional fields are not provided, the table upload will use the default function.

var newCompanyAction = controllerMappings.newTableActionHandlerBuilder()
    .id('newCompanyImportActions')
    .title('New company import actions')
    .description('Create new company (orgs)')
    .transformRowFn('doTransformRow')
    .processRowFn('doProcessRow');
newCompanyAction.field("orgIdPrefix", "Org ID Prefix", true);
newCompanyAction.field("defaultOrgType", "Default Org Type", true).optionsFn(function () {
    var list = formatter.newArrayList();
    formatter.foreach(services.organisationManager.allOrgTypes, function(orgType){
        list.add(orgType.name);
    });
    
    return list;
});
newCompanyAction.build();

You will see the action in the table uploader action selection

Implement custom functions

We will implement the detail in doTransformRow and doProcessRow, he details of the functions are changed by your requirement. In this example, we will use these function to handle two requirements:

• If Org Id Prefix is provided, automatically add the prefix to the organisation ID
• If Default Org Type is selected, automatically add all organisations in the file to the selected organisation type

Input data

Upload action

Upload mapping

Result

Implements

You can see in the input file and mapping, we will see two issues:

• It does not contains the prefix in the input file
• The organisation type does not existed in the input file. Even if the field is existed in the file, it does not mapped in the mapping

To resolve these issues, we will implement function handler for transformRowFn  and processRownFn:

• transformRowFn is handled by doTransformRow
• processRownFn is handled by doProcessRow

function doTransformRow(row, params, rowContext, importContext){
    var orgIdPrefix = params.orgIdPrefix;
    if ( formatter.isNotEmpty(orgIdPrefix) ) {
        var orgId = formatter.safeGet(row, 0);
        if ( formatter.isNotEmpty(orgId) ) {
            orgId = orgIdPrefix + orgId;
        }
        row.set(0, formatter.cleanString(orgId)); //Modify the first element
    }
    
    var defaultOrgType = params.defaultOrgType;
    if ( formatter.isNotEmpty(defaultOrgType) ) {
        row.add(defaultOrgType); //Add the org type to the end of row data (Index = 3)
    }
    
    return row;
}

Each row in the input file will be transform to an array list (the first parametter in the function), and each cell in the row will be an element of the array list.

- Add the prefix: The Company ID is mapped to Org ID, and it is first element of the array list, so we will modify the first element of the array list.

- Add the organistion type to the row data: The transform function cannot process the organisation data, it only prepare the data for the process function. As you can see, the row have not contains the value for organisation type, so we will add the org type to the end of the row data (In this case, it is the fourth element). Then we will process this element in the doProcessRow

function doProcessRow(row, params, rowContext, importContext){
    var fieldMappings = rowContext.fieldMappings;

    if (fieldMappings && formatter.isNotEmpty(fieldMappings)) {
        var typeMap = formatter.newArrayList();
        typeMap.add(3); //The index of the org type in row data
        fieldMappings.put('orgTypeName', typeMap);
    }
}

In the doProcessRow, we will modify the current mapping and add the org type (orgTypeName) to the mapping. The field will look for the org type value in the row data by its index